Cream of the Crop 26/Cream of the Crop 26.iso/comm/ftpdif10.zip/READ.ME

Text File | 1997-07-09 | 18KB | 327 lines

FTPDIF FTP-index utility - finds differences in FTP directory listings
Version 1.0, program written by Tim D. Kannel (TDK)
Copyright(c) 1997  Tim Kannel

This program is freeware. It may be freely distributed as long as this
READ.ME file is present.
Date READ.ME last updated: 7/9/97

A listing of program options can be obtained with the '/?' command-line
parameter. Options are also described in this file.

Contents:
  - Description/Purpose (short)
  - Disclaimer/License Agreement (Important legal information)
  - Usage information (syntax, description of options)
  - Description (long)
  - Known Problems
  - Contact Information (bug reporting,etc.)
  - Future releases
  - Other information (obtaining source code, other programs by TDK)


  Description (short)
  -----------
    FTPDIF finds differences in FTP directory listings and writes
  a new file that indicates those differences. Items that did not change
  are also written to the new file (the output file is therefore a
  complete listing, modified to indicate changes in the two versions).
  This program is an alternative to newsgroup announcements and
  mailing lists.

  Disclaimer / License Agreement - Please Read!
  ------------------------------
    The author of this program assumes NO liability for
  use of this program, whether that be damage to your computer or
  copyright issues regarding the reproduction of FTP index files.
  Some (or all) FTP sites have reproduction copyrights on their directory
  listings. Improper use of this program may violate those copyrights.
  This program is intended to be for PERSONAL USE ONLY; the output from
  this program should not posted in any way without permission from
  the managers of the FTP site from which the index files were taken.
  This program is supplied as-is. There are NO expressed or implied
  warranties.
    This program is not based on any other program. It was
  developed indepently by the author.

  Usage Information (command-line syntax)
  -----------------
    FTPDIF [options] older-file newer-file [out-file]
           older-file  name of file that is out-of-date
           newer-file  name of file that is more recent
           out-file    override default and set output file name
    Options:   /?        display help information
               /N        suppress 'NEW' messages in out-file
               /F        suppress 'NOT FOUND' messages in out-file
               /A        suppress all unnecessary output (options /N and /F)
               /B        allow both sets of special characters
               /Clist    change the special characters to those in 'list'

    File names may contain complete paths; wildcard characters in the
    file names are not allowed.
    Note that FTPDIF does not examine the file dates to see which one
    is newer; it depends only on the order of the names on the command-line.
    Options may be indicated with a dash or with a slash.
    For example, both "/?" and "-?" (without the quotes) are
    valid (and identical) options.

  Options described in a little more detail:
    (The strings (without the quotes) "OLD","NEW", and "OUTPUT" refer to
    the respective files given on the command-line. These are just
    descriptive labels for describing the program in the rest of this file.)

  - Output file name('out-file'): specify the name for the new index file.
    Default filename is derived from the newer index file and uses the
    ".NEW" extension. Exampe: if the second command-line parameter
    (the newer index file) is INDEX.TXT, the output file is INDEX.NEW.
  - /N: Suppress "NEW" messages in OUTPUT (directories and filenames)
  - /F: Suppress (directory)"NOT FOUND" messages in OUTPUT
  - /A: Suppress both message types (this is equivalent to specifying
    both the /N and /F options)
  - /B: allow both sets of special characters (special characters are
    written from OLD AND from NEW).
  - /C change the list of special characters - the default set of special
    characters is overwritten with the specified list, up to 10 characters
    may be specified. Note that specifying an empty list will effectively
    disable checking for special characters. The characters must be
    immediately after the 'C'; no spaces are allowed.

  These should be more clear after reading the program description...

  Description (long)
  -----------
    Parts of this description may seem out of order, but everything will
  hopefully be clear in the end (I'm a programmer, not a writer!)
    FTPDIF takes two input files that are assumed to be ASCII index lists
  of the files contained on an FTP site. (The indices should originate from
  the same directory on the site). One input file should be a newly
  obtained index (NEW) and one should be an older file that may have special
  modifier-characters as described below (OLD). The directory listings
  are processed one at a time, while looking for differences. A new output
  file (OUTPUT) is created that is similar to NEW, except with the following
  modifications:

     - files present in NEW but not present in OLD are added to OUTPUT
       with the addition of the string "**NEW**" at the beginning of the
       line (without the quotes).
     - files present in OLD but not in NEW are assumed to have been deleted;
       a message is written out indicating that these files weren't found
       (this message will probably just be the filename, not the full
       description). These messages will be grouped at the end of each
       directory and will be of the form "** FILE NOT FOUND: filename **",
       where filename is the name of the file.
     - directories are indicated in a similar manner, except the strings
       are "** DIRECTORY NOT FOUND: dirname **" (where dirname is the name
       of the directory) and "** NEW DIRECTORY **". The former type of
       directory messages are grouped at the beginning of OUTPUT before
       the listings start.
     - FTPDIF recognizes several special characters regarding the status
       of files. These special characters are only interpreted as such if
       they appear at the beginning of a line in front of a file name.
       These characters are used to keep a record of interesting files to
       be downloaded (or record those that already have been downloaded).
       A description follows:

       @   get next time
       %   get some time in the future
       ^   already downloaded
       ^-  downloaded and deleted (some of these may be marked as ^)
       ?   unknown/undecided (possibly download)

       It is possibly to override this set of characters with the /C
       command-line option. If this option is used, you will be prompted
       for descriptions one at a time. This 'special-characters' feature
       can be disabled by not listing any characters after the '/C'.

       These indicators are by no means required. Their purpose is for
       you to know what files are of interest to you.
       These characters are generally discarded from NEW so that duplicates
       don't occur in front of the filename (this can overrided with the
       /B command-line option, in which the special characters are written
       from OLD first and then the special characters from NEW are written.
       There is a limit to how many characters can be considered
       'special' for each file name. Also note that, contrary to what is
       indicated above, special characters are always considered
       individually, not as a group. Special characters, if new ones
       are specified, should be designed to be located easily (since their
       purpose is to locate files of interest to you) and to not interfere
       with file names (e.g., periods would be a bad choice).

       Status indicators

         When FTPDIF begins processing a new directory, a status message
       will be displayed showing the name of the directory currently being
       processed. Errors generated during processing should relate to
       the directory currently being shown.

       Special Cases (technical details, these do not need to be
          understood to successfully use the program)
          - Any lines that are not of the form
            "FILENAME<spaces>DESCRIPTION" are passed on to OUTPUT as-is.
            This includes lines at the top of NEW and other lines in NEW
            such as those that indicate a directory name.
          - Directory mismatches:
              - directories present in NEW but not present in OLD are
                written to OUTPUT as-is (no line processing is done)
              - directories present in OLD but not present in NEW (an
                unlikely occurrence) are NOT written to OUTPUT. A single
                line is written that notifies you of the change:
                "**DIRECTORY NOT FOUND: dirname**", where dirname is the name
                of the directory that was apparently removed. The actual
                files from that directory are not written to OUTPUT.
                (You might want to check this before deleting OLD; note that
                such messages will appear as a group before the main portion
                of the file.)
           - hyphen vs. underscore: any hyphens found in file-names will
               be converted to underscores. Although this is done for
               comparison purposes (at least one FTP site changed their
               filenames in this fashion, so it was necessary to do this),
               this does mean that listings where a name is supposed to have
               a hyphen will not (because it was converted to an underscore).
           - parsing: the number of significant characters is relatively
               short (current implementation only recognizes 32 characters).
               This means that directory names with full paths will not
               be processed in their entirety. However, the characters that
               are considered significant are at the end of the name string
               (part of the path gets removed, not the name of the specific
               directory). File names also have a length limitation, but it
               is considerably longer (128 characters).
               This should NOT affect the correctness of FTPDIF's output.

       Methods of detecting directories (more technical details)
         - lines containing the string "DIRECTORY" (without the quotes,
           case insensitive) are considered to be indicating directories
           unless it appears that it is part of a description. (This latter
           part is determined by also looking for a filename at the start
           of the line). If a line does contain that string, the directory
           name is assumed to be the word after it. (This method works for
           FTP sites such as X2FTP and Simtel.)
         - lines with a single word following by a colon (possibly with
           whitespace in-between). The directory name is then the word that
           started the line. (This method works for sites such as Garbo.)

       File versions
         Files that have been replaced with a newer version, with even
       a slight change in file name, will be interpreted as being
       new files. Be aware of this fact when looking for files specified
       as being new. This will hopefully be improved in a future version.
       For now, you can verify if a version change was the cause by
       looking for a 'NOT FOUND' message at the end of the directory
       for the old version of that file.

  Known Bugs/Limitations
  --------------------------

  - No detection of version changes (file replacements).
  - FTPDIF does not recognize its own output. For example, filenames with
    the string "**NEW**" in front will not be recognized as filenames.
    Most likely the entire line will be treated as garbage and will be
    ignored. To avoid difficulties with this bug, use an editor to search
    and delete such strings before using a file output by FTPDIF as input
    to FTPDIF later on. Correcting this bug will be a priority if any
    more versions are developed.
  - as mentioned above, hyphens are converted to underscores for
    comparison purposes. The filename that is output does not necessarily
    match the input because of this. (This bug is easy to fix, but makes
    the source code more complex.)

  Note: this program requires about 200Kb of conventional memory;
  anything less than that and the program will run slowly or won't even
  execute. (But who doesn't have 200Kb of free memory?)

  Contact Information
  -------------------
    Please send bug reports, comments, or suggestions to the email address
  listed below.

    Program author:
       Tim Kannel
           Computer Science junior, University of Minnesota - Twin Cities
       email: [e-mail]

  If nothing else, please send email saying that you downloaded the
  program. I'm interested in knowing how many people are using it.
    This program was tested on directory listings (index files) from
  X2FTP (x2ftp.oulu.fi), a Simtel site (uiarchive.cso.uiuc.edu),
  and Garbo (garbo.uwasa.fi). If this program does not work with listings
  from these or other FTP sites, please contact the author; specify
  the URL for the site and exactly what file was being used. It might
  also be helpful to attach the older index to the email message.

  Future Releases
  ---------------
    If enough people use and like this program a second version will
  be developed.
  Features/Fixes to be included:
    - sort directories
    - sort files within each directory
    - create a log file of changes made  (as a separate record from
        the index itself)
    - fixes to the problems listed above

    The sort options aren't likely to be useful, since FTP sites generally
  have directories and files listed in an orderly fashion anyway, but this
  feature would be simple to implement (it was part of the design for
  this version, just not implemented).

  Other Information
  -----------------
    C++ source code is available upon request (it may already be included
  with the .ZIP archive). Send email to address above.
  Tested with Borland C++ 3.1 and Borland C++ 5.0. Releases compiled with
  Borland 3.1 (version 5.0 produced a much larger executable).

  Other Programs/Libraries by Tim Kannel
    Note: none of these have been released publicly, but may be available
      from the author; see the information below.
    - TCAP - TSR program to capture text output; works under DOS
        (screws up majorly under Win95). Captures output by intercepting
        the video BIOS character and string output functions.
    - CRLF - program to convert Unix linefeeds to DOS
        carriage-return/linefeeds (There are other programs available to
        do this, so this one wasn't worth releasing).
    - IVIEW - image viewer - supports GIF,PCX,Windows BMP,Targa,
        PBM/PGM/PPM, and PNG (for those of you who haven't heard, PNG is
        a new format designed to replace GIF).
        I'd release this program as shareware but if I did that I'd have to
        remove the GIF support (I don't care to get the licence from Unisys),
        and the program is slow (probably because it uses a lot of EMS memory.
        A protected mode port of this program is possible in the future, which
        should make it faster). Supports scaling images and scrolling
        (except both at once is buggy at the moment, and it slows to a crawl).
        Command-line based, supports wildcards and multiple
        file specifications. Includes a slide show feature.
    - VESA SVGA library - only supports 256-color modes. (I tried added
      direct-color support, but my video system doesn't support true-color
      and it hi-color support is buggy. That makes it rather hard to test
      the code.). IVIEW uses the 256-color version of the library.
    - C++ EMS-memory library (used by IVIEW). Provides a C++ class to
      encapsulate EMS memory operations.
    - buffered file I/O - C++ class to buffer file reads. Currently does
      not support writes (most programs do more file reading than writing
      anyway); read buffering can be easily disabled (in which
      case file I/O drops through to standard library functions, normally it
      calls DOS through inline assembly). Improves program performance
      tremendously, but using C++ streams (which are buffered) would be
      a better choice for most applications. (This library could be easily
      converted to C if anyone wants to avoid C++. For that matter, it
      could be ported to straight assembly without much trouble.)
      IVIEW also uses this class (one of the fast parts of that program).
    - planned: bit-stream C++ class to read/write files as bit streams,
      instead of whole bytes. (This is easy to do as simple functions, but
      encapsulating it as an object (i.e. class instance) would be more
      OOP-like). The class would inherit from the standard I/O classes.
      Actually there would be two or three classes: ifbitstream, ofbitstream,
      and possibly fbitstream (based on ifstream,ofstream, and fstream).
      The number of bits to read/write would be variable with each call
      (with a default of 8 to easily support normal byte operations).

  If you're interested in any of these, send email; but no guarantees.
  (CRLF I'll definitely give you (with C++ source), TCAP probably (but not
  with the .ASM source), IVIEW probably (but will only include C++ source
  if you want to help develop it - adding file support is quite easy),
  the SVGA library isn't worth releasing unless you want something small
  with only 256-color support).

END READ.ME  (anyone actually read all of this?)